'.\" t
.TH "clconf.xml" "1M" "Jan 20, 2008" "1\&.4\&.1"
.SH NAME
clconf.xml \- Main Linuxha.net Cluster Configuration File

.SH SYNOPSIS
Defines Linuxha.net Cluster Configuration Topology

A sample configuration file may look similar to the following:

.TS
l.
<?xml version="1.0"?>
<clconf>
        <global>
                <name>cluster1</name>
                <version>0.1</version>
                <data>replicated</data>
                <datadetail>drbd</datadetail>
                <dataprotocol>C</dataprotocol>
                <logdir>/var/log/cluster</logdir>
                <key>keyhere</key>
                <portpool>9901,9999</portpool>
                <maxblockdevs>50</maxblockdevs>
                <drbd_network>drbd</drbd_network>
                <net_reuse>2.5</net_reuse>
                <parallel>0</parallel>
                <alert_to>you@email</alert_to>
        </global>
        <timings>
                <keepalive>1</keepalive>
                <warn>3</warn>
                <dead>6</dead>
                <clusterform>120</clusterform>
        </timings>
        <node>
                <name>servera</name>
                <network name="a" cards="eth0,eth1" reusetime="2"/>
                <network name="b" cards="eth2" attributes="crossover"/>
        </node>
        <node>
                <name>serverb</name>
                <network name="a" cards="eth0,eth1" reusetime="2"/>
                <network name="b" cards="eth2" attributes="crossover"/>
        </node>
        <net_known_connections>
                www.bbc.co.uk
        </net_known_connections>
</clconf>
.TE

.SH THE GLOBAL SECTION
The globals section defines general characteristics for the cluster. Unless
specified below the entries are mandatory.

.TS
center box ;
l l.
Variable	Purpose
_
name	The name of the cluster - should be a single word
	consisting of alpha numerics and underscores.
version	The version of the configuration file. The expected value
	for current releases of Linuxha.net is "0.1".
data	The type of cluster. At the moment only "replicated" is
	supported - support for "shared" will be introduced in later
	releases. This defines how the data is managed - replicated
	meaning each node has a copy of the data.
datadetail	The type of replication that takes place. At the moment
	on "drbd" is supported.
logdir	The directory to write logs to. Optional - will default to
	"/var/log/cluster" if not present.
key	The key to use for all cluster communication. This should be
	treated as a password. The cluster will not start if anyone
	other than root is able to read the file.
portpool	A lower,higher comma-separarated range of numebers which
	define ports that can be allocated to cluster application
	communications.
maxblockdevs	The maximum nuber of Data synchronisation devices that the
	cluster can supported - a maximum of 64 of Linux 2.4 and 256
	on Linux 2.6.
drbd_network	The name of the logical network that should be used
	in the cluster for data replication traffic. Ideally this should
	be a dedicated network but it can be the same as one that is
	used to host application IP addresses if necessary.
net_reuse	The default time before a network connection can be
	considered for reuse in seconds. This is optional and if
	not specified will default to 5.
parallel	The default mode when a node fails is that all
	applications that were running on the failed node
	are restarted one at a time on the remaining node.
	If the machines are multi-processor or multi-core then
	changing this to 1 will attempt to start all times
	at the same time. This may reduce the total fail-over
	time depending on machine hardware.
alert_to	If present is used to define an email address that can
	be used for the cluster to send messages to the system
	administrator to indicate when certain conditions have
	occurred, such as nodes failing, or applications starting.
.TE

.SH THE TIMINGS SECTION
This section contains the default settings that various components of the cluster software
used to determine the maximum period of time that should elapse before taking 
further action.

In this section all timings are given in seconds, and should be whole numbers. 
This gives a minimum interval available is 1 second.
.TS
center box ;
l l.
Variable	Purpose
_
keepalive	This defines how often the cluster daemons attempt to 
	communicate with one another. The recommended value is 
	between 1 and 5 seconds.
warn	The elapsed time that must occur before a warning is given
	indicating communication between the two cluster daemons
	is not available. This must be larger than the keepalive
	value, and is typically 3 seconds.
dead	The number of seconds after loosing contact with the other
	cluster node after which the other node should be considered
	dead. At this point in time the remaining cluster server will
	start to take over cluster resources where relevant.
clusterform	The amount of time to wait for the other node in the
	cluster to become available when the cluster is formnig, or
	a node is attempting to join an existing cluster. The 
	efault is 300 seconds - a period of time which should be
	longer than the required reboot time of the slowest server
	in the cluster.
.TE

.SH The NODE SECTIONS
For each node in the cluster a separate "node" section is present. The
"node" elements not only define the names of the networks but also
determine the node network topology. Hence the node definition may contain
only a single "name" element, but 0, 1 or more "network" elements to define
the topology of the node in question.

.TS
center box ;
l l.
Variable	Purpose
_
name	The hostname of the server for which this section applies.
	This must match the output of the \fIhostname(1)\fP command on
	the server.
network	Defines one or more cards that make up the specified logical network
	on the host. This element should contain two mandatory attributes -
	"name" and "cards". The "name" is a single word which is a label for
	this network, whilst "cards" is a comma-separated list of network
	cards on this node that from this network.
attributes	Any attributes that defines the network connection. This
	is optional and the only setting currently available is "crossover"
	to indicate the network connection is not to a switch but 
	directly to the other machine in the cluster.
reusetime	Allows the default card reuse time to be over-wridden on
	a per-network basis. 
.TE

.SS Network Configurtion
The "network" elements for each node are responsible for defining the
cluster network topology. There are some basic rules that must be 
followed when defining this information.

.TP 4
.B [1]
Each node must define the same networks. The order of the definitions does
not need to be the same - nor do the card names or even number of cards.
.TP
.B [2]
Each network must contain at least one network card. There is no upper limit.
.TP
.B [3]
A network card can only be specified in a single network. All cards defined
in a network must be logical part of the same subnet.
.TP
.B [4]
One, and only one, card of those defined in a network must have an IP address
on each node. This IP address is known as the 'static' IP address for that
network on that node. This IP addresses (and those of any application IP
addresses using that network), will migrate to another card if a physical
or logical problem with the current network card occurs.
.TP
.B [5]
To support automatic fail-over all cards in a network definition should 
support the MII level checks. See the installation guide for the current
list of supported chipsets.

.SH The Known Network Connection Section
This section is totally optional though it is strongly recommended that
it is added. It simply contains some well known hosts that are external
from the cluster - though it should be reachable with ICMP pings from
both nodes in the cluster.

This information is used to help ascertain whether a node in the cluster
is unavailable or whether a network issue has occured. Although not
fool-proof it does help avoid certain conditions.

.SH SEE ALSO
.TS
l l.
clbuild(1M)	- Build / Validate cluster topology
cldeamon(1M)	- Cluster status Daemon
appconf.xml(5)	- Configuration of an application used by the cluster
.TE

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
http://linuxha.net/index.pl?ARGS=findproject:linuxha for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

